@Part[Preds, Root = "CLM.MSS"]
@Comment{Chapter of Common Lisp Manual.  Copyright 1984 Guy L. Steele Jr.⎇


@MyChapter[Predicates]
@Label[PREDS]

A @Def[predicate] is a function that tests for some condition involving
its arguments and returns @false if the condition is false, or some
non-@false value if the condition is true.  One may think of a predicate as
producing a Boolean value, where @false stands for @i[false] and anything
else stands for @i[true].  Conditional control structures such as
@Macref[cond],
@Specref[if], @Macref[when], and @Macref[unless] test such Boolean values.
We say that a predicate @i[is true] when it returns a non-@false value,
and @i[is false] when it returns @false; that is, it is true or false
according to whether the condition being tested is true or false.
@Index2[P {predicates⎇, S {true and false⎇]
@Index2[P {true⎇, S {when a predicate is⎇]
@Index2[P {false⎇, S {when a predicate is⎇]

By convention, the names of predicates usually end in the letter
@f[p] (which stands for ``predicate'').
@Index2[P {naming conventions⎇, S {predicates⎇]
@clisp uses a uniform convention in hyphenating names of predicates.
If the name of the predicate is formed by adding a @f[p] to
an existing name, such as the name of a data type,
a hyphen is placed before the final @f[p] if and only if there is
a hyphen in the existing name.  For example, @f[number] begets @f[numberp]
but @f[standard-char] begets @f[standard-char-p].
On the other hand, if the name of a predicate is formed by adding
a prefixing qualifier to the front of an existing predicate name,
the two names are joined with a hyphen and the presence or absence
of a hyphen before the final @f[p] is not changed.  For example,
the predicate @f[string-lessp] has no hyphen before the @f[p]
because it is the string version of @f[lessp] (a @maclisp function
that has been renamed @f[<] in @clisp).  The name @f[string-less-p]
would incorrectly imply that it is a predicate that tests for a kind
of object called a @f[string-less], and the name @f[stringlessp]
would connote a predicate that tests whether something has no strings
(is ``stringless'')!

The control structures that test Boolean values only test for
whether or not the value is @false, which is considered to be false.  Any
other value is considered to be true.  Often a predicate will return @false if
it ``fails'' and some @i[useful] value if it ``succeeds'';
such a function can be used not only as a test but
also for the useful value provided in case of success.  An example
is @Funref[member].

If no better non-@nil value is available for the purpose of indicating
success, by convention the symbol @f[t] is used as the ``standard''
true value.

@Section[Logical Values]

The names @f[nil] and @f[t] are constants in @clisp.  Although they
are symbols like any other symbols, and appear to be treated
as variables when evaluated, it is not permitted to modify their
values.  See @f[defconstant].

@Defcon[Var {nil⎇]
The value of @nil is always @nil.  This object represents the logical
@i[false] value and also the empty list.  It can also be written @f[()].
@Enddefcon

@Defcon[Var {t⎇]
The value of @f[t] is always @f[t].
@Enddefcon

@Section[Data Type Predicates]

Perhaps the most important predicates in @xlisp are those that deal
with data types;  that is, given a data object one can determine whether
or not it belongs to a given type, or one can compare two type specifiers.

@Subsection[General Type Predicates]

If a data type is viewed as the set of all objects belonging to the type,
then the @f[typep] function is a set membership test, while @f[subtypep]
is a subset test.

@Defun[Fun {typep⎇, Args {@i[object] @i[type]⎇]
@f[typep] is a predicate that
is true if @i[object] is of type @i[type], and is false otherwise.
Note that an object can be ``of'' more than one type, since one type can
include another.  The @i[type] may be any of the type specifiers
mentioned in chapter @Ref[DTSPEC] @i[except] that it may not
be or contain a type specifier list whose first element is @f[function]
or @f[values].
A specifier of the form @f[(satisfies @i[fn])] is handled simply
by applying the function @i[fn] to @i[object]
(see @Funref[funcall]); the @i[object] is considered
to be of the specified type if the result is not @false.
@Enddefun

@Defun[Fun {subtypep⎇, Args {@i[type1] @i[type2]⎇]
The arguments must be type specifiers that are acceptable to @Funref[typep].
The two type specifiers are compared; this predicate is true
if @i[type1] is definitely a (not necessarily proper) subtype of @i[type2].
If the result is @false, however, then @i[type1] may or may not be a subtype of
@i[type2] (sometimes it is impossible to tell, especially when
@f[satisfies] type specifiers are involved).
A second returned value indicates the certainty of the result;
if it is true, then the first value is an accurate indication
of the subtype relationship.  Thus there are three possible
result combinations:
@Begin[Format]
@tabset[+.4in,+1 in]
@true@\@true@\@i[type1] is definitely a subtype of @i[type2]
@false@\@true@\@i[type1] is definitely not a subtype of @i[type2]
@false@\@false@\@f[subtypep] could not determine the relationship
@End[Format]
@Enddefun

@Subsection[Specific Data Type Predicates]

The following predicates test for individual data types.
@Index2[P {data type⎇, S {predicates⎇]

@Defun[Fun {null⎇, Args {@i[object]⎇]
@Index2[P {empty list⎇, S {predicate⎇]
@f[null] is true if its argument is @empty,
and otherwise is false.
This is the same operation performed by the function @Funref[not];
however, @f[not] is normally used to invert a Boolean value,
whereas @f[null] is normally used to test for an empty list.  The programmer
can therefore express @i[intent] by the choice of function name.
@Lisp
(null x) @EQ (typep x 'null) @EQ (eq x '@empty)
@Endlisp
@Enddefun

@Defun[Fun {symbolp⎇, Args {@i[object]⎇]
@Index2[P {symbol⎇, S {predicate⎇]
@f[symbolp] is true if its argument is a symbol,
and otherwise is false.
@Lisp
(symbolp x) @EQ (typep x 'symbol)
@Endlisp
@Incompatibility{The @interlisp equivalent of @f[symbolp] is
called @f[litatom].⎇
@Enddefun

@Defun[Fun {atom⎇, Args {@i[object]⎇]
@Index2[P {atom⎇, S {predicate⎇]
The predicate @f[atom] is true if its argument is not a cons,
and otherwise is false.
Note that @f[(atom '@empty)] is true, because @empty@Sail[≡]@nil.
@Lisp
(atom x) @EQ (typep x 'atom) @EQ (not (typep x 'cons))
@Endlisp
@Incompatibility{In some @xlisp dialects, notably @interlisp,
only symbols and numbers are considered to be atoms; arrays
and strings are considered to be neither atoms nor lists (conses).⎇
@Enddefun

@Defun[Fun {consp⎇, Args {@i[object]⎇]
@Index2[P {cons⎇, S {predicate⎇]
The predicate @f[consp] is true if its argument is a cons,
and otherwise is false.
Note that the empty list is not a cons, so
@f[(consp '@empty)] @EQ @f[(consp '@nil)] @EV @nil.
@Lisp
(consp x) @EQ (typep x 'cons) @EQ (not (typep x 'atom))
@Endlisp
@Incompatibility{Some @xlisp implementations call this function
@f[pairp] or @f[listp].  The name @f[pairp] was rejected for @clisp
because it emphasizes too strongly the dotted-pair notion rather than the
usual usage of conses in lists.  On the other hand, @f[listp] too strongly
implies that the cons is in fact part of a list, which after all it might
not be; moreover, @empty is a list, though not a cons.
The name @f[consp] seems to be the appropriate compromise.⎇
@Enddefun

@Defun[Fun {listp⎇, Args {@i[object]⎇]
@Index2[P {list⎇, S {predicate⎇]
@f[listp] is true if its argument is a cons or the empty list @empty,
and otherwise is false.  It does not check for whether the list
is a ``true list'' (one terminated by @nil) or a ``dotted list''
(one terminated by a non-null atom).
@Lisp
(listp x) @EQ (typep x 'list) @EQ (typep x '(or cons null))
@Endlisp
@Enddefun

@Defun[Fun {numberp⎇, Args {@i[object]⎇]
@Index2[P {number⎇, S {predicate⎇]
@f[numberp] is true if its argument is any kind of number,
and otherwise is false.
@Lisp
(numberp x) @EQ (typep x 'number)
@Endlisp
@Enddefun

@Defun[Fun {integerp⎇, Args {@i[object]⎇]
@Index2[P {integer⎇, S {predicate⎇]
@f[integerp] is true if its argument is an integer, and otherwise
is false.
@Lisp
(integerp x) @EQ (typep x 'integer)
@Endlisp
@Incompatibility{In @maclisp this is called @f[fixp].
Users have been confused as to whether this meant @f[integerp]
or @f[fixnump], and so the name @f[integerp] has been adopted here.⎇
@Enddefun

@Defun[Fun {rationalp⎇, Args {@i[object]⎇]
@Index2[P {rational⎇, S {predicate⎇]
@f[rationalp] is true if its argument is a rational number (a ratio or
an integer), and otherwise is false.
@Lisp
(rationalp x) @EQ (typep x 'rational)
@Endlisp
@Enddefun

@Defun[Fun {floatp⎇, Args {@i[object]⎇]
@Index2[P {floating-point number⎇, S {predicate⎇]
@f[floatp] is true if its argument is a floating-point number,
and otherwise is false.
@Lisp
(floatp x) @EQ (typep x 'float)
@Endlisp
@Enddefun

@Defun[Fun {complexp⎇, Args {@i[object]⎇]
@Index2[P {complex number⎇, S {predicate⎇]
@f[complexp] is true if its argument is a complex number,
and otherwise is false.
@Lisp
(complexp x) @EQ (typep x 'complex)
@Endlisp
@Enddefun

@Defun[Fun {characterp⎇, Args {@i[object]⎇]
@Index2[P {character⎇, S {predicate⎇]
@f[characterp] is true if its argument is a character,
and otherwise is false.
@Lisp
(characterp x) @EQ (typep x 'character)
@Endlisp
@Enddefun

@Defun[Fun {stringp⎇, Args {@i[object]⎇]
@Index2[P {string⎇, S {predicate⎇]
@f[stringp] is true if its argument is a string,
and otherwise is false.
@Lisp
(stringp x) @EQ (typep x 'string)
@Endlisp
@Enddefun

@Defun[Fun {bit-vector-p⎇, Args {@i[object]⎇]
@Index2[P {bit-vector⎇, S {predicate⎇]
@f[bit-vector-p] is true if its argument is a bit-vector,
and otherwise is false.
@Lisp
(bit-vector-p x) @EQ (typep x 'bit-vector)
@Endlisp
@Enddefun

@Defun[Fun {vectorp⎇, Args {@i[object]⎇]
@Index2[P {vector⎇, S {predicate⎇]
@f[vectorp] is true if its argument is a vector,
and otherwise is false.
@Lisp
(vectorp x) @EQ (typep x 'vector)
@Endlisp
@Enddefun

@Defun[Fun {simple-vector-p⎇, Args {@i[object]⎇]
@Index2[P {vector⎇, S {predicate⎇]
@f[vectorp] is true if its argument is a simple general vector,
and otherwise is false.
@Lisp
(simple-vector-p x) @EQ (typep x 'simple-vector)
@Endlisp
@Enddefun

@Defun[Fun {simple-string-p⎇, Args {@i[object]⎇]
@Index2[P {simple string⎇, S {predicate⎇]
@f[simple-string-p] is true if its argument is a simple string,
and otherwise is false.
@Lisp
(simple-string-p x) @EQ (typep x 'simple-string)
@Endlisp
@Enddefun

@Defun[Fun {simple-bit-vector-p⎇, Args {@i[object]⎇]
@Index2[P {simple bit-vector⎇, S {predicate⎇]
@f[simple-bit-vector-p] is true if its argument is a simple bit-vector,
and otherwise is false.
@Lisp
(simple-bit-vector-p x) @EQ (typep x 'simple-bit-vector)
@Endlisp
@Enddefun

@Defun[Fun {arrayp⎇, Args {@i[object]⎇]
@Index2[P {array⎇, S {predicate⎇]
@f[arrayp] is true if its argument is an array,
and otherwise is false.
@Lisp
(arrayp x) @EQ (typep x 'array)
@Endlisp
@Enddefun

@Defun[Fun {packagep⎇, Args {@i[object]⎇]
@Index2[P {package⎇, S {predicate⎇]
@f[packagep] is true if its argument is an package,
and otherwise is false.
@Lisp
(packagep x) @EQ (typep x 'package)
@Endlisp
@Enddefun

@Defun[Fun {functionp⎇, Args {@i[object]⎇]
@Index2[P {function⎇, S {predicate⎇]
@f[functionp] is true if its argument is suitable for applying
to arguments, using for example the @f[funcall] or @f[apply] function.
Otherwise @f[functionp] is false.

@f[functionp] is always true of symbols, lists whose @i[car]
is the symbol @f[lambda], any value returned by the @Specref[function]
special form, and any values returned by the function @Funref[compile]
when the first argument is @nil.
@Enddefun

@Defun[Fun {compiled-function-p⎇, Args {@i[object]⎇]
@Index2[P {compiled function⎇, S {predicate⎇]
@f[compiled-function-p] is true if its argument is any compiled code object,
and otherwise is false.
@Lisp
(compiled-function-p x) @EQ (typep x 'compiled-function)
@Endlisp
@Enddefun

@Defun[Fun {commonp⎇, Args {@i[object]⎇]
@Index2[P {common data type⎇, S {predicate⎇]
@f[commonp] is true if its argument is any standard @clisp data type,
and otherwise is false.
@Lisp
(commonp x) @EQ (typep x 'common)
@Endlisp
@Enddefun

See also @Funref[standard-char-p], @Funref[string-char-p],
@Funref[streamp], @Funref[random-state-p],
@Funref[readtablep],
@Funref[hash-table-p], and @Funref[pathnamep].

@Section[Equality Predicates]

@clisp provides a spectrum of predicates for testing for equality of
two objects: @f[eq] (the most specific), @f[eql], @f[equal], and @f[equalp]
(the most general).  @f[eq] and @f[equal] have the meanings traditional
in @xlisp.  @f[eql] was added because it is frequently needed, and
@f[equalp] was added primarily in order to have a version of @f[equal]
that would ignore type differences when comparing numbers
and case differences when comparing characters.
If two objects satisfy any one of these equality predicates,
then they also satisfy all those that are more general.

@Defun[Fun {eq⎇, Args {@i[x] @i[y]⎇]
@f[(eq @i[x] @i[y])] is true
if and only if @i[x] and @i[y] are the same identical object.
(Implementationally, @i[x] and @i[y] are usually
@f[eq] if and only if they address the same identical memory location.)

It should be noted that things that print the same are not necessarily @f[eq]
to each other.  Symbols with the same print name usually are @f[eq] to
each other because of the use of the @Funref[intern] function.
However, numbers with the same value
need not be @f[eq], and two similar lists are usually not @f[eq].
@Findex2[P {eq⎇, S {compared to @f[equal]⎇]
For example:
@lisp
(eq 'a 'b) @r[is false.]
(eq 'a 'a) @r[is true.]
(eq 3 3) @r[might be true or false, depending on the implementation.]
(eq 3 3.0) @r[is false.]
(eq 3.0 3.0) @r[might be true or false, depending on the implementation.]
(eq #c(3 -4) #c(3 -4)) @r[might be true or false, depending on the implementation.]
(eq #c(3 -4.0) #c(3 -4)) @r[is false.]
(eq (cons 'a 'b) (cons 'a 'c)) @r[is false.]
(eq (cons 'a 'b) (cons 'a 'b)) @r[is false.]
(eq '(a . b) '(a . b)) @r[might be true or false.]
(progn (setq x (cons 'a 'b)) (eq x x)) @r[is true.]
(progn (setq x '(a . b)) (eq x x)) @r[is true.]
(eq #\A #\A) @r[might be true or false, depending on the implementation.]
(eq "Foo" "Foo") @r[might be true or false.]
(eq "Foo" (copy-seq "Foo")) @r[is false.]
(eq "FOO" "foo") @r[is false.]
@Endlisp
In @clisp, unlike some other @xlisp dialects, the implementation
is permitted to make ``copies'' of
characters and numbers at any time.  (This permission is granted
because it allows tremendous performance improvements in many
common situations.)  The net effect is that
@clisp makes no guarantee that @f[eq] will be true even when both
its arguments are ``the same thing'' if that thing is a character or number.
For example:
@lisp
(let ((x 5)) (eq x x)) @r[might be true or false.]
@endlisp
The predicate @f[eql] is the same as @f[eq], except that if the
arguments are characters or numbers of the same type then their
values are compared.  Thus @f[eql] tells whether two objects
are @i[conceptually] the same, whereas @f[eq] tells whether two
objects are @i[implementationally] identical.  It is for this reason
that @f[eql], not @f[eq], is the default comparison predicate
for the sequence functions defined in chapter @ref[KSEQUE].

@Implementation{@f[eq] simply compares the two given pointers,
so any kind of object that is represented in an ``immediate'' fashion
will indeed have like-valued instances satisfy @f[eq].
In some implementations, for example,
fixnums and characters happen to ``work.''
However, no program should depend on this, as other implementations
of @clisp might not use an immediate representation for these data types.⎇

An additional problem with @f[eq] is that the implementation is permitted
to ``collapse'' constants (or portions thereof)
appearing in code to be compiled if they are
@f[equal].  An object is considered to be a constant in code to be compiled
if it is a self-evaluating form or is contained in a @Specref[quote] form.
This is why @f[(eq "Foo" "Foo")] might be true or false; in interpreted
code it would normally be false, because reading in the
form @f[(eq "Foo" "Foo")] would construct distinct strings for the two
arguments to @f[eq], but the compiler might choose to use the same
identical string or two distinct copies as the two arguments in the
call to @f[eq].  Similarly, @f[(eq '(a . b) '(a . b))] might be true
or false, depending on whether the constant conses appearing in the
@f[quote] forms were collapsed by the compiler.  However,
@f[(eq (cons 'a 'b) (cons 'a 'b))] is always false, because every distinct
call to the @f[cons] function necessarily produces a new and distinct cons.
@Enddefun

@Defun[Fun {eql⎇, Args {@i[x] @i[y]⎇]
The @f[eql] predicate is true if its arguments are @f[eq],
or if they are numbers of the same type with the same value,
or if they are character objects
that represent the same character.
For example:
@lisp
(eql 'a 'b) @r[is false.]
(eql 'a 'a) @r[is true.]
(eql 3 3) @r[is true.]
(eql 3 3.0) @r[is false.]
(eql 3.0 3.0) @r[is true.]
(eql #c(3 -4) #c(3 -4)) @r[is true.]
(eql #c(3 -4.0) #c(3 -4)) @r[is false.]
(eql (cons 'a 'b) (cons 'a 'c)) @r[is false.]
(eql (cons 'a 'b) (cons 'a 'b)) @r[is false.]
(eql '(a . b) '(a . b)) @r[might be true or false.]
(progn (setq x (cons 'a 'b)) (eql x x)) @r[is true.]
(progn (setq x '(a . b)) (eql x x)) @r[is true.]
(eql #\A #\A) @r[is true.]
(eql "Foo" "Foo") @r[might be true or false.]
(eql "Foo" (copy-seq "Foo")) @r[is false.]
(eql "FOO" "foo") @r[is false.]
@Endlisp
Normally @f[(eql 1.0s0 1.0d0)] would be false, under the assumption
that @f[1.0s0] and @f[1.0d0] are of distinct data types.
However, implementations that do not provide four distinct floating-point
formats are permitted to ``collapse'' the four formats into some
smaller number of them; in such an implementation @f[(eql 1.0s0 1.0d0)]
might be true.  The predicate @Xfunref[X {=⎇, L {#&M⎇] will compare
the values of two numbers even if the numbers are of different types.

If an implementation supports positive and negative zeros as distinct
values (as in the @c[IEEE] proposed standard floating-point format),
then @f[(eql 0.0 -0.0)] will be false.  Otherwise, when the syntax
@f[-0.0] is read it will be interpreted as the value @f[0.0],
and so @f[(eql 0.0 -0.0)] will be true.  The predicate @Xfunref[X {=⎇, L {#&M⎇]
differs from @f[eql] in that @f[(= 0.0 -0.0)] will always be true,
because @f[=] compares the mathematical values of its operands,
whereas @f[eql] compares the representational values, so to speak.

Two complex numbers are considered to be @f[eql]
if their real parts are @f[eql] and their imaginary parts are @f[eql].
For example, @f[(eql #C(4 5) #C(4 5))] is true and
@f[(eql #C(4 5) #C(4.0 5.0))] is false.
Note that while @f[(eql #C(5.0 0.0) 5.0)] is false,
@f[(eql #C(5 0) 5)] is true.
In the case of @f[(eql #C(5.0 0.0) 5.0)] the
two arguments are of different types,
and so cannot satisfy @f[eql]; that's all there is to it.
In the case of @f[(eql #C(5 0) 5)], however,
@f[#C(5 0)] is not a complex number, but
is always automatically reduced by the rule of complex
canonicalization to the integer @f[5],
just as the apparent ratio @f[20/4] is always simplified to @f[5].

The case of @f[(eql "Foo" "Foo")] is discussed above in the description
of @Funref[eq].  While @f[eql] compares the values of numbers and
characters, it does not compare the contents of strings.  To compare
the characters of two strings, one should use @f[equal], @f[equalp],
@Xfunref[X {string=⎇, L {string#&M⎇], or @Funref[string-equal].

@Incompatibility{The @clisp function @f[eql] is similar to the
@interlisp function @f[eqp].  However, @f[eql] considers @f[3] and
@f[3.0] to be different, whereas @f[eqp] considers them to be the same;
@f[eqp] behaves like the @clisp @f[=] function, not like @f[eql],
when both arguments are numbers.⎇
@Enddefun

@Defun[Fun {equal⎇, Args {@i[x] @i[y]⎇]
The @f[equal] predicate is true if its arguments are structurally similar
(isomorphic) objects.  A rough rule of thumb is that two objects
are @f[equal] if and only if their printed representations are the same.

Numbers and characters are compared as for @f[eql].
Symbols are compared as for @f[eq].  This method
of comparing symbols can violate the rule
of thumb for @f[equal] and printed representations,
but only in the infrequently occurring case of two distinct
symbols with the same print name.

Certain objects that have components are @f[equal] if they are of the same
type and corresponding components are @f[equal].
This test is implemented in a recursive manner and may fail to
terminate for circular structures.

For conses, @f[equal] is defined recursively as
the two @i[car]'s being @f[equal] and the two @i[cdr]'s being @f[equal].

Two arrays are @f[equal] only if they are @f[eq],
with one exception:
strings and bit-vectors are compared element-by-element.
If either argument has a fill pointer, the fill pointer limits
the number of elements examined by @f[equal].
Uppercase and lowercase letters in strings are considered by
@f[equal] to be distinct.  (In contrast, @f[equalp] ignores
case distinctions in strings.)

@Incompatibility{In @lmlisp, @f[equal] ignores the difference between
uppercase and lowercase letters in strings.
This violates the rule of thumb about
printed representations, however, which is very useful, especially
to novices.  It is also inconsistent with the treatment of single characters,
which in @lmlisp are represented as fixnums.⎇

Two pathname objects are @f[equal] if and only if
all the corresponding components
(host, device, and so on) are equivalent.  (Whether or not
uppercase and lowercase letters are considered equivalent
in strings appearing in components depends on the file
name conventions of the file system.)  Pathnames
that are @f[equal] should be functionally equivalent.

@lisp
(equal 'a 'b) @r[is false.]
(equal 'a 'a) @r[is true.]
(equal 3 3) @r[is true.]
(equal 3 3.0) @r[is false.]
(equal 3.0 3.0) @r[is true.]
(equal #c(3 -4) #c(3 -4)) @r[is true.]
(equal #c(3 -4.0) #c(3 -4)) @r[is false.]
(equal (cons 'a 'b) (cons 'a 'c)) @r[is false.]
(equal (cons 'a 'b) (cons 'a 'b)) @r[is true.]
(equal '(a . b) '(a . b)) @r[is true.]
(progn (setq x (cons 'a 'b)) (equal x x)) @r[is true.]
(progn (setq x '(a . b)) (equal x x)) @r[is true.]
(equal #\A #\A) @r[is true.]
(equal "Foo" "Foo") @r[is true.]
(equal "Foo" (copy-seq "Foo")) @r[is true.]
(equal "FOO" "foo") @r[is false.]
@Endlisp
To compare a tree of conses, using @f[eql]
(or any other desired predicate) on the leaves, use @Funref[tree-equal].
@Enddefun

@Defun[Fun {equalp⎇, Args {@i[x] @i[y]⎇]
Two objects are @f[equalp] if they are @f[equal];
if they are characters and satisfy @Funref[char-equal],
which ignores alphabetic case and certain other attributes of characters;
if they are numbers and have the same numerical value,
even if they are of different types;
or if they have components that are all @f[equalp].

Objects that have components are @f[equalp] if they are of the same
type and corresponding components are @f[equalp].
This test is implemented in a recursive manner and may fail to
terminate for circular structures.
For conses, @f[equalp] is defined recursively as
the two @i[car]'s being @f[equalp] and the @i[two cdr]'s being @f[equalp].

Two arrays are @f[equalp] if and only if they have the same
number of dimensions, the dimensions match,
and the corresponding components are @f[equalp].
The specializations need not match; for example,
a string and a general array that happens to contain the same characters
will be @f[equalp] (though definitely not @f[equal]).
If either argument has a fill pointer, the fill pointer limits
the number of elements examined by @f[equalp].
Because @f[equalp] performs element-by-element comparisons
of strings and ignores the alphabetic case of characters,
case distinctions are therefore also ignored when @f[equalp] compares
strings.

Two symbols can be @f[equalp] only if they are @f[eq], that is, the same
identical object.

@lisp
(equalp 'a 'b) @r[is false.]
(equalp 'a 'a) @r[is true.]
(equalp 3 3) @r[is true.]
(equalp 3 3.0) @r[is true.]
(equalp 3.0 3.0) @r[is true.]
(equalp #c(3 -4) #c(3 -4)) @r[is true.]
(equalp #c(3 -4.0) #c(3 -4)) @r[is true.]
(equalp (cons 'a 'b) (cons 'a 'c)) @r[is false.]
(equalp (cons 'a 'b) (cons 'a 'b)) @r[is true.]
(equalp '(a . b) '(a . b)) @r[is true.]
(progn (setq x (cons 'a 'b)) (equalp x x)) @r[is true.]
(progn (setq x '(a . b)) (equalp x x)) @r[is true.]
(equalp #\A #\A) @r[is true.]
(equalp "Foo" "Foo") @r[is true.]
(equalp "Foo" (copy-seq "Foo")) @r[is true.]
(equalp "FOO" "foo") @r[is true.]
@Endlisp
@Enddefun

@Section[Logical Operators]

@Index2[P {logical operators⎇, S {on @false and non-@false values⎇]
@clisp provides three operators on Boolean values: @f[and], @f[or],
and @f[not].  Of these, @f[and] and @f[or]
are also control structures because their arguments are evaluated
conditionally.
The function @f[not] necessarily examines its single argument, and so
is a simple function.

@Defun[Fun {not⎇, Args {@i[x]⎇]
@f[not] returns @true if @i[x] is @false, and otherwise returns @false.
It therefore inverts its argument considered as a Boolean value.

@Funref[null] is the same as @f[not]; both functions are included for the sake
of clarity.  As a matter of style,
it is customary to use @f[null] to check whether something is the empty list
and to use @f[not] to invert the sense of a logical value.
@Enddefun

@Defmac[Fun {and⎇, Args {@Mstar<@i[form]>⎇]
@Index2[P {conditional⎇, S {@f[and]⎇]
@f[(and @i[form1] @i[form2] ... )] evaluates each @i[form], one at a time,
from left to right.  If any @i[form] evaluates to @false, the value @nil
is immediately returned without evaluating the remaining
@i[forms].  If every @i[form] but the last evaluates to a non-@false value,
@f[and] returns whatever the last @i[form] returns.
Therefore in general @f[and] can be used both for logical operations,
where @false stands for @i[false] and non-@false values stand for @i[true],
and as a conditional expression.
For example:
@lisp
(if (and (>= n 0)
	 (< n (length a-simple-vector))
	 (eq (elt a-simple-vector n) 'foo))
    (princ "Foo!"))
@Endlisp
The above expression prints @f[Foo!] if element @f[n] of @f[a-simple-vector]
is the symbol @f[foo], provided also that @f[n] is indeed a valid index
for @f[a-simple-vector].  Because @f[and] guarantees left-to-right testing
of its parts, @f[elt] is not called if @f[n] is out of range.

To put it another way,
the @f[and] special form does @i[short-circuit] Boolean evaluation,
like the @b[and then] operator in @ada
and what in some @pascal-like languages is called @b[cand] (for ``conditional
and''); the @xlisp @f[and] special form is
unlike the @pascal or @ada @b[and] operator,
which always evaluates both arguments.

In the previous example writing
@Lisp
(and (>= n 0)
     (< n (length a-simple-vector))
     (eq (elt a-simple-vector n) 'foo)
     (princ "Foo!"))
@Endlisp
would accomplish the same thing.  The difference is purely stylistic.
Some programmers never use expressions containing side effects
within @f[and], preferring to use @f[if] or @f[when] for that purpose.

From the general definition, one can deduce that
@f[(and @i[x])] @EQ @i[x].  Also,
@f[(and)] evaluates to @true, which is an identity for this operation.

One can define @f[and] in terms of @Macref[cond] in this way:
@Lisp
(and @i[x] @i[y] @i[z] ... @i[w]) @EQ (cond @!((not @i[x]) @false)
@/((not @i[y]) @false)
@/((not @i[z]) @false)
@/...
@/(@true @i[w]))
@Endlisp

See @Specref[if] and @Macref[when], which are sometimes stylistically
more appropriate than @f[and] for conditional purposes.
If it is necessary to test whether a predicate is true
of all elements of a list or vector (element 0 @i[and] element 1 @i[and]
element 2 @i[and]...), then the function @Funref[every] may be useful.
@Enddefmac

@Defmac[Fun {or⎇, Args {@Mstar<@i[form]>⎇]
@Index2[P {conditional⎇, S {@f[or]⎇]
@f[(or @i[form1] @i[form2] ... )] evaluates each @i[form], one at a time,
from left to right.  If any @i[form] other than the last
evaluates to something other than @false,
@f[or]
immediately returns that non-@false value without evaluating the remaining
@i[forms].  If every @i[form] but the last evaluates to @false,
@f[or] returns whatever evaluation of the last of the @i[forms] returns.
Therefore in general @f[or] can be used both for logical operations,
where @false stands for @i[false] and non-@false values stand for @i[true],
and as a conditional expression.

To put it another way,
the @f[or] special form does @i[short-circuit] Boolean evaluation,
like the @b[or else] operator in @ada
and what in some @pascal-like languages is called @b[cor] (for ``conditional
or''); the @xlisp @f[or] special form is
unlike the @pascal or @ada @b[or] operator,
which always evaluates both arguments.

From the general definition, one can deduce that
@f[(or @i[x])] @EQ @i[x].  Also,
@f[(or)] evaluates to @nil, which is the identity for this operation.

One can define @f[or] in terms of @Macref[cond] in this way:
@Lisp
(or @i[x] @i[y] @i[z] ... @i[w]) @EQ (cond (@i[x]) (@i[y]) (@i[z]) ... (@true @i[w]))
@Endlisp

See @Specref[if] and @Macref[unless], which are sometimes
stylistically more appropriate than @f[or] for conditional purposes.
If it is necessary to test whether a predicate is true
one or more elements of a list or vector (element 0 @i[or] element 1 @i[or]
element 2 @i[or]...), then the function @Funref[some] may be useful.
@Enddefmac